home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 10 / AACD 10.iso / AACD / Graphics / picsize / picsize.readme < prev    next >
Text File  |  2000-01-09  |  10KB  |  274 lines
  1. Short:    Shows picture dimensions using datatypes
  2. Kurz:     Zeigt Bildausmaße anhand Datatypes
  3. Author:   amiga@rripley.de (Ralph Reuchlein)
  4. Uploader: amiga@rripley.de (Ralph Reuchlein)
  5. Type:     util/dtype
  6. Version:  1.2
  7. Date:     26-Dec-1999
  8. Replaces: util/dtype/picsize.lha
  9.  
  10.                                PicSize
  11.                                =======
  12.  
  13.  
  14. PURPOSE
  15.  
  16.    The archive contains a small program to determine picture
  17.    dimensions including the sources.
  18.  
  19.    Since I am working alot with images that were downloaded from
  20.    Aminet or other internet sources, were made by myself or were
  21.    generated by software, sometimes its useful to list image
  22.    dimensions instead of showing them or using other image viewers
  23.    with verbose output.
  24.  
  25.    This picture dimension determiner is based on the datatypes system
  26.    which is available since OS 3.0. Therefore you can scan each image
  27.    which datatype you have installed on your system.
  28.  
  29.    The sources is only one C source :-) This file should be compatible
  30.    to each compiler and contains features like Templates and
  31.    ReadArgs(), functions with variable arguments, a pseudo RawDoFmt()
  32.    function and -of course- the (simple) datatype handling.
  33.  
  34.  
  35.  
  36. HISTORY
  37.  
  38.    v1.2:
  39.    - a bugfix (I forgot a return statement in my most important
  40.      function, thanks to Jerome Chesnot)
  41.    - added file size information format type %s
  42.    - changed filename suffix format type %s to %e (to avoid conflict
  43.      with the added file size information format type)
  44.    - corrected BUGS section of this readme
  45.  
  46.    v1.1:
  47.  
  48.    The first version of Picsize (released at 25-Mar-1999) had only
  49.    some switches for specific output. It wasn't good enough for me and
  50.    I now have built in a format string feature for various output
  51.    strings. This version now also got a version string.
  52.  
  53.  
  54.  
  55. INSTALL
  56.  
  57.    Simply unpack the archive to anywhere you want. I prefer to copy
  58.    the executable to C:.
  59.  
  60.  
  61.  
  62. REQUIREMENTS
  63.  
  64.    - OS 3.0
  65.    - datatypes for your image types
  66.  
  67.  
  68.  
  69. USAGE
  70.  
  71.    The template is
  72.  
  73.       FILE/A,FORMAT=FMT,INTRODUCER=INTR/K
  74.  
  75.    You always have to provide the image file you want to determine.
  76.    Using only the first option you will get full information about
  77.    the image:
  78.  
  79.       » picsize amiga8.jpg
  80.       DATA1:Images/Amiga/amiga8.jpg: 336x502x24 [JFIF]
  81.  
  82.    Column 1 displays the filename (with path, even when you didn't
  83.    provided one), then the image dimension with width, height and
  84.    depth is shown and finally the internal base name of the datatype
  85.    is displayed.
  86.  
  87.    The option FORMAT allows you to define an own output string. The
  88.    default format string is
  89.  
  90.       "%f: %wx%hx%d [%t]"
  91.  
  92.    The format types are:
  93.  
  94.       %n    basename of the file (the filename without path)
  95.       %f    full filename including path (even, when you didn't
  96.             provided one)
  97.       %P    path name including trailing '/' and ':'
  98.       %p    path name excluding trailing '/', but with ':'
  99.             (warning: there are different cases of the two 'p'!)
  100.       %o    basename of the file without suffix
  101.       %e    suffix of the file including leading '.'
  102.       %w    width of image
  103.       %h    height of image
  104.       %d    depth of image
  105.       %t    image type
  106.       %s    file size
  107.  
  108.    Each format type can be formatted like the printf() function from
  109.    the C standard libraries. There is only one restriction: You cannot
  110.    add a type qualifier to the type, e.g. "%lw" (must only be "%w").
  111.    Some examples of formatting:
  112.  
  113.       %30n  Basename will be displayed in a 30 column wide space. If
  114.             the basename length is less than 30, it will be right
  115.             filled by spaces.
  116.       %-30n Equals %30n, but field will be left filled by spaces.
  117.       %.4n  Truncates basename to 4 characters or will be right filled
  118.             if name length is less than 4.
  119.       %04w  Writes width of image in a 4 column wide field. If the
  120.             number has less than 4 digits, it will be left filled with
  121.             zeros instead of spaces.
  122.  
  123.    For more information refer to the C standard library documentation
  124.    of printf(), sprintf() or fprintf().
  125.  
  126.    Finally the INTRODUCER option (you have to use the keyword
  127.    INTRODUCER or INTR to specify this option) changes the default
  128.    format type introducer character '%' to another value. This is
  129.    useful for scripting to avoid collisions with other programs using
  130.    '%' as introducer too.
  131.  
  132.  
  133. EXAMPLES
  134.  
  135.    Following table shows the format types and its output, when the
  136.    file "amiga8.jpg" is used:
  137.  
  138.       %n    amiga8.jpg
  139.       %f    DATA1:Images/amiga8.jpg
  140.       %P    DATA1:Images/
  141.       %p    DATA1:Images
  142.       %o    amiga8
  143.       %e    .jpg
  144.       %w    336
  145.       %h    502
  146.       %d    24
  147.       %t    JFIF
  148.       %s    47906
  149.  
  150.    You might miss a format type for a full filename without suffix,
  151.    but its really no problem, because you simply need to concatenate
  152.    format types to
  153.  
  154.       %P%o
  155.  
  156.    which leads to
  157.  
  158.       DATA1:Images/amiga8
  159.  
  160.    Voilá.
  161.  
  162.    The main purpose of picsize is scripting. For example you can use
  163.    the script s:SPAT for a simple picture list:
  164.  
  165.       s:SPAT picsize IMAGES:xfiles/scully#? "INTR $" *"$-30n  $wx$hx$d, $t*"
  166.  
  167.    which prints:
  168.  
  169.       > s:spat picsize IMAGES:xfiles/scully#? "INTR $" *"$-30n  $wx$hx$d, $t*"
  170.       scully03.jpg                    522x317x24, JFIF
  171.       scully02.jpg                    476x328x24, JFIF
  172.       scully01.jpg                    476x365x24, JFIF
  173.  
  174.    You have to replace the introducer character to '$', because s:spat
  175.    uses the '%' introducers for itself (s:spat uses LIST LFORMAT).
  176.  
  177.    Another example includes the command substitution feature of
  178.    CLI/Shell:
  179.  
  180.       > rename scully02.jpg as `picsize scully02.jpg "%o_%wx%h%s"`
  181.  
  182.    This one would rename the file "scully02.jpg" as
  183.    "scully02_476x328.jpg".
  184.  
  185.  
  186.  
  187. BUGS
  188.  
  189.    Unfortunately there is a bug - or better to say: insufficency -,
  190.    but don't blame me for that, because the error lies in the
  191.    datatypes.
  192.  
  193.    Most of the datatypes were based on the example provided by
  194.    Commodore. This example shows creating the image data in a
  195.    DISPLAYABLE memory area during the OM_NEW method. So the picture
  196.    datatypes like ilbm.datatype or jfif.datatype first unpack the
  197.    image to CHIP RAM, then build up a BitMap structure and finally a
  198.    BitMapHeader structure. The BitMapHeader structure holds the
  199.    information like width, height, depth and so on. If you now try to
  200.    open a huge image which bitmap can't be build in CHIP MEM due to
  201.    insufficient memory, picsize returns an error. Until now everything
  202.    works fine, but now the bug strikes back: You might detect that the
  203.    datatype system grabbed a huge portion of CHIP RAM and the datatype
  204.    forgot to free it! You have no chance to free that unused memory;
  205.    the only thing is a reboot. This bug may lie in the
  206.    picture.datatype you use. For the datatypes developers back to
  207.    image creation: During OM_NEW there is no need for image creation,
  208.    maybe later at OM_DRAW. (Thanks to Gunther Nikl for the background
  209.    information)
  210.  
  211.    But ...
  212.  
  213.    Good news for CyberGraphX V3/V4 users: CGFX has a environment
  214.    variable PLANES2FAST which allowes swapping unused bitmaps to FAST
  215.    RAM. If the variable is set to 1, the datatype system build the
  216.    bitmaps in FAST RAM. If you have 64 MB RAM, you can determine very
  217.    huge images without having a memory bug as described above. The
  218.    variable unfortunately has some negative side effects: Each program
  219.    assuming a bitmap in CHIP RAM would access on a non-allocated area
  220.    in CHIP RAM (remember, the bitmap is swapped to FAST RAM!) that
  221.    surely leads to system crashes.
  222.  
  223.  
  224.  
  225. DISCLAIMER
  226.  
  227.    THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS"
  228.    AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  229.    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  230.    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR
  231.    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  232.    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  233.    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  234.    USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  235.    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  236.    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  237.    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  238.    SUCH DAMAGE.
  239.  
  240.  
  241.  
  242. MISC
  243.  
  244.    Suggestions and bug reports are welcome, but I think the little
  245.    program's purpose is fully accomplished.
  246.  
  247.    It is my first experience in programming datatypes, so I still have
  248.    some questions:
  249.    1) Is it possible to avoid decoding the image data, if I only want
  250.       the image dimensions? This would speed up the processing alot.
  251.    2) Why I can't force DTA_GroupID,GID_PICTURE at NewDTObject? When I
  252.       use a picture it works fine, but when using e.g. an executable,
  253.       first a new Object will be created, but I can't access its
  254.       attributes, because my machine shows me an red alert 'privilege
  255.       violation'. According to the datatype autodocs it should not
  256.       create a new object and return a ERROR_OBJECT_WRONG_TYPE in
  257.       IoErr(). Is there a bug? The only way I can use is feeding it
  258.       without any attributes at object generation. Did I something
  259.       wrong there?
  260.  
  261.  
  262. CONTACT
  263.  
  264.    snail  Ralph Reuchlein
  265.    mail:  Eibseestr. 18c
  266.           86163 Augsburg
  267.           GERMANY
  268.    
  269.    eMail: amiga@rripley.de
  270.    WWW:   http://www.rripley.de
  271.    IRC:   RRipley on #germany
  272.  
  273.  
  274.